9-1 数据库迁移流程&代码版本控制
在完成权限系统的全部开发后（RBAC + Policy + Menu），本节进行项目里程碑保存：数据库迁移（Migration）+ 数据备份（SQL Export）+ 版本控制（Git Tag），确保项目可作为模板复用。
一、保存前的项目状态
当前项目已完成三套权限控制体系的数据库设计与接口实现：
| 权限类型 | 数据库表 | 接口功能 |
|---|---|---|
| RBAC 角色权限 | Role, Permission, RolePermission | 用户-角色-权限 CRUD |
| 策略权限 | Policy, RolePolicy, PermissionPolicy | CASL Ability + PolicyGuard |
| 菜单权限 | Menu, MenuMeta, RoleMenu | 树形菜单 CRUD + 角色关联 |
二、数据库保存的两步流程
第一步：创建 Prisma Migration
# 创建迁移记录（会重置数据库，注意备份数据）
npx prisma migrate dev --name base_v1
bash
执行过程：
? The following data will be lost:
- Table `User` (all rows)
- Table `Role` (all rows)
...
Do you want to continue? → Y (确认)
Applying migration `20260519_base_v1`
text
注意：
migrate dev会清空数据库数据。如果数据库中有重要的测试数据，需要先导出备份。
迁移名称约定：
| 命名 | 含义 |
|---|---|
base_v1 | 基础模板 V1，包含完整的权限系统 |
add_business_module | 新增业务模块 |
alter_menu_schema | 修改菜单 Schema |
第二步：导出数据库结构和数据
使用数据库管理工具（如 pgAdmin、DBeaver）导出完整的数据库：
# pgAdmin 导出步骤
1. 右键数据库 → 导出 (Export)
2. 勾选"表结构 + 数据" (Format: Custom, Compression: gzip)
3. 选择 SQL + gzip 格式
4. 执行导出
bash
推荐格式：SQL + gzip（压缩后体积更小，导入时兼容性更好）
三、Prisma 迁移命令对比
| 命令 | 用途 | 适用环境 | 数据影响 |
|---|---|---|---|
prisma db push | 同步 Schema 到数据库 | 开发（原型阶段） | 可能丢失数据 |
prisma migrate dev | 创建迁移文件并应用 | 开发 | 会重置数据 |
prisma migrate deploy | 应用已提交的迁移 | 生产 | 不丢失数据 |
prisma migrate reset | 重置数据库到初始状态 | 开发 | 全部清空 |
最佳实践：开发阶段用
migrate dev管理迁移历史，生产环境只用migrate deploy。生产环境绝对不要使用migrate dev或db push。
四、Git 版本控制
1. 提交代码并添加 Tag
# 提交当前代码
git add .
git commit -m "feat: v1.0 权限控制系统完成"
# 创建带注释的 Tag
git tag -a v1.0.0 -m "v1.0.0 - 完整的RBAC+Policy+Menu权限系统"
# 推送代码和 Tag 到远端
git push origin main
git push origin v1.0.0
bash
2. 使用 Tag 拉取模板项目
# 基于 Tag 克隆项目
git clone --branch v1.0.0 <repo-url>
# 或在已有项目中切换到指定版本
git checkout v1.0.0
bash
3. Tag vs Branch
| 方式 | 命令 | 适用场景 |
|---|---|---|
| Tag | git tag -a v1.0.0 | 标记里程碑版本，不可变 |
| Branch | git branch v1.0.0 | 需要在此基础上继续开发 |
建议：对于模板项目保存，Tag 比 Branch 更合适。Tag 标记的是一个确定的版本快照，不会被意外修改。
五、数据库恢复
后续开发需要恢复数据库时，导入之前导出的 SQL 文件：
# pgAdmin 导入步骤
1. 右键数据库 → 导入 (Import)
2. 选择之前导出的 .sql.gz 文件
3. 取消勾选"出错时停止" (Continue on error)
4. 执行导入
bash
关于导入错误：
- 导入过程中可能出现大量错误（如 DROP TABLE、CREATE TABLE 失败）
- 这些错误通常是因为目标数据库中已存在对应的表结构
- 数据插入操作会正常执行，测试数据得以恢复
- 可以忽略这些结构性的错误
六、完整的保存与恢复流程
┌─────────────── 保存阶段 ───────────────┐
│ │
│ 1. npx prisma migrate dev --name v1 │
│ → 创建迁移记录 │
│ │
│ 2. 数据库导出 (SQL + gzip) │
│ → 保存表结构 + 测试数据 │
│ │
│ 3. git tag -a v1.0.0 │
│ → 标记代码版本 │
│ │
│ 4. git push origin v1.0.0 │
│ → 推送到远端 │
│ │
└─────────────────────────────────────────┘
┌─────────────── 恢复阶段 ───────────────┐
│ │
│ 1. git clone --branch v1.0.0 <url> │
│ → 拉取模板代码 │
│ │
│ 2. npx prisma migrate deploy │
│ → 应用迁移，创建表结构 │
│ │
│ 3. 数据库导入 (SQL + gzip) │
│ → 恢复测试数据 │
│ │
│ 4. pnpm install && pnpm dev │
│ → 安装依赖，启动开发服务 │
│ │
└─────────────────────────────────────────┘
text
七、最佳实践总结
| 实践 | 说明 |
|---|---|
| 阶段性备份 | 完成一个系统模块后立即备份数据库 |
| 干净的测试数据 | 备份前清理脏数据，确保导出的数据可用 |
| 迁移文件纳入 Git | prisma/migrations/ 目录应提交到版本控制 |
| Tag 标记里程碑 | 每个重要版本使用语义化版本号打 Tag |
| 区分环境命令 | 开发用 migrate dev，生产用 migrate deploy |
| 保留模板版本 | 后续新业务可基于 v1.0.0 的 Tag 快速初始化 |
八、后续开发流程
基于 v1.0.0 模板项目，后续的业务开发流程：
# 1. 基于 Tag 创建新的开发分支
git checkout -b feature/business v1.0.0
# 2. 新增业务 Schema
# 编辑 prisma/schema.prisma → 添加新的 Model
# 3. 创建迁移
npx prisma migrate dev --name add_business_module
# 4. 使用 NestJS CLI 生成模块
nest g resource modules/business --no-spec
# 5. 开发业务接口...
bash
权限系统作为基础设施已经完备，后续只需专注于业务逻辑的实现。
↑